/**
 * @copyright Copyright (c) 2025 CSG Digital Grid Technology (Guangdong) Co., Ltd.
 * @author Xie Jinhui
 */

/* Define to prevent recursive inclusion -------------------------------------*/
/* This preprocessor directive prevents multiple inclusion of the same header file */
/* Ensuring the header contents are only processed once during compilation */
#ifndef __APN_H
#define __APN_H

/* Standard integer type inclusion for fixed-width integer definitions */
/* Provides uint8_t, uint16_t, etc. for precise memory allocation control */
#include <stdint.h>

/**
 * @brief Maximum number of APN configurations supported by the system
 * This constant defines the upper limit for stored APN profiles to prevent
 * memory overflow and ensure predictable system behavior
 */
#define APN_NUM 16

/**
 * @brief Maximum character length for APN name strings
 * This defines the buffer size allocated for storing APN names including
 * null terminator to prevent buffer overflow vulnerabilities
 */
#define APN_NAME_LEN 128

/**
 * @brief Maximum character length for IP address strings
 * Defines the buffer size for storing IPv4 addresses in dotted-decimal
 * format (e.g., "192.168.1.1") including null termination
 */
#define ROUTE_IP_LEN 16

/**
 * @brief Maximum number of routing table entries supported
 * This constant limits the number of IP routing entries that can be
 * configured and managed by the routing subsystem
 */
#define ROUTE_IP_NUM 128

/**
 * @brief Maximum character length for JSON configuration strings
 * Defines the buffer size for storing complete JSON configuration data
 * including APN settings, routing information, and system parameters
 */
#define JSON_LEN 2048

/**
 * @brief String identifier for China Mobile carrier configuration
 * This constant provides a standardized name for China Mobile carrier
 * specific APN settings and network configurations
 */
#define MOBILE_CARRIER "Mobile"

/**
 * @brief String identifier for China Unicom carrier configuration
 * This constant provides a standardized name for China Unicom carrier
 * specific APN settings and network configurations
 */
#define UNICOM_CARRIER "Unicom"

/**
 * @brief String identifier for China Telecom carrier configuration
 * This constant provides a standardized name for China Telecom carrier
 * specific APN settings and network configurations
 */
#define TELECOM_CARRIER "Telecom"

/**
 * @brief Add new APN configuration to the system
 * This function creates and registers a new Access Point Name configuration
 * with the specified parameters for cellular data connection establishment
 * @return uint8_t Returns TRUE if APN added successfully, FALSE if operation failed
 *                 due to invalid parameters or system constraints
 */
extern uint8_t wwwan_apn_add(void);

/**
 * @brief Display APN configuration for specified network device
 * This function retrieves and prints the current APN settings configured
 * for a specific network interface device for user verification and debugging
 * @param dev: Character pointer specifying the target network device name
 *             (e.g., "ppp0", "ppp1" for cellular interfaces)
 * @return uint8_t Returns TRUE if APN information displayed successfully,
 *                 FALSE if device not found or configuration unavailable
 */
extern uint8_t wwan_apn_show(char *dev);

/**
 * @brief Delete specific APN configuration by numerical index
 * This function removes a single APN configuration entry identified by
 * its positional index from the specified network device's configuration
 * @param dev: Character pointer specifying the target network device name
 *             from which the APN configuration should be removed
 * @param num: Character pointer to string containing the numerical index
 *             of the APN configuration to be deleted (1-based indexing)
 * @return uint8_t Returns TRUE if APN deleted successfully, FALSE if index
 *                 invalid or deletion operation failed
 */
extern uint8_t wwan_apn_delete_one(char *dev, char *num);

/**
 * @brief Delete all APN configurations for specific carrier
 * This function removes all APN configurations associated with a particular
 * cellular network carrier from the specified network device configuration
 * @param dev: Character pointer specifying the target network device name
 *             from which carrier-specific APNs should be removed
 * @param carrier_name: Character pointer specifying the carrier identifier
 *                     (e.g., "Mobile", "Unicom", "Telecom") for bulk deletion
 * @return uint8_t Returns TRUE if all carrier APNs deleted successfully,
 *                 FALSE if carrier not found or deletion operation failed
 */
extern uint8_t wwan_apn_delete_carrier(char *dev, char *carrier_name);

/**
 * @brief Initialize APN configuration file with default settings
 * This function creates or resets the APN configuration file with default
 * values and carrier-specific presets for system initialization scenarios
 * @param file_string: Character pointer to buffer containing the initial
 *                    configuration data or file path for initialization
 * @return uint8_t Returns TRUE if configuration file initialized successfully,
 *                 FALSE if file creation failed or invalid parameters provided
 */
extern uint8_t config_file_apn_Init(char *file_string);

#endif /* __APN_H */